home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / tclX6.4c / dist / tcllib / help / status / history < prev    next >
Encoding:
Text File  |  1992-11-10  |  8.0 KB  |  153 lines
  1.           history ?option? ?arg arg ...?
  2.                Note:  this command may not be available  in  all  Tcl-
  3.                based applications.  Typically, only those that receive
  4.                command  input  in  a  typescript  form  will   support
  5.                history.   The  history command performs one of several
  6.                operations  related   to   recently-executed   commands
  7.                recorded  in  a  history  list.  Each of these recorded
  8.                commands  is  referred  to  as  an   ``event''.    When
  9.                specifying   an  event  to  the  history  command,  the
  10.                following forms may be used:
  11.  
  12.                [1]  A number:  if positive, it  refers  to  the  event
  13.                     with that number (all events are numbered starting
  14.                     at 1).  If the number is negative, it  selects  an
  15.                     event  relative to the current event (-1 refers to
  16.                     the previous event, -2 to the one before that, and
  17.                     so on).
  18.  
  19.                [2]  A string:  selects  the  most  recent  event  that
  20.                     matches  the  string.   An  event is considered to
  21.                     match the string either if the string is the  same
  22.                     as  the  first  characters of the event, or if the
  23.                     string matches the  event  in  the  sense  of  the
  24.                     string match command.
  25.  
  26.                The history command  can  take  any  of  the  following
  27.                forms:
  28.  
  29.                history
  30.                     Same as history info, described below.
  31.  
  32.                history add command ?exec?
  33.                     Add the command argument to the history list as  a
  34.                     new  event.  If exec is specified (or abbreviated)
  35.                     then the command is also executed and  its  result
  36.                     is  returned.   If  exec  isn't  specified then an
  37.                     empty string is returned as result.
  38.  
  39.                history change newValue ?event?
  40.                     Replace the  value  recorded  for  an  event  with
  41.                     newValue.   Event  specifies the event to replace,
  42.                     and defaults to the current event (not event  -1).
  43.                     This  command is intended for use in commands that
  44.                     implement new forms of  history  substitution  and
  45.                     wish  to  replace the current event (which invokes
  46.                     the substitution) with the command created through
  47.                     substitution.    The  return  value  is  an  empty
  48.                     string.
  49.  
  50.                history event ?event?
  51.                     Returns the value of the  event  given  by  event.
  52.                     Event defaults to -1.  This command causes history
  53.                     revision to occur: see below for details.
  54.  
  55.                history info ?count?
  56.                     Returns a formatted string (intended for humans to
  57.                     read)  giving  the  event  number and contents for
  58.                     each of the events in the history list except  the
  59.                     current  event.   If  count is specified then only
  60.                     the most recent count events are returned.
  61.  
  62.                history keep count
  63.                     This command may be used to change the size of the
  64.                     history  list  to  count  events.   Initially,  20
  65.                     events are retained in  the  history  list.   This
  66.                     command returns an empty string.
  67.  
  68.                history nextid
  69.                     Returns  the  number  of  the  next  event  to  be
  70.                     recorded  in  the  history list.  It is useful for
  71.                     things like printing the event number in  command-
  72.                     line prompts.
  73.  
  74.                history redo ?event?
  75.                     Re-execute the  command  indicated  by  event  and
  76.                     return  its  result.   Event defaults to -1.  This
  77.                     command results in history  revision:   see  below
  78.                     for details.
  79.  
  80.                history substitute old new ?event?
  81.                     Retrieve  the  command  given  by  event  (-1   by
  82.                     default), replace any occurrences of old by new in
  83.                     the command (only  simple  character  equality  is
  84.                     supported;  no  wild cards), execute the resulting
  85.                     command, and return the result of that  execution.
  86.                     This  command  results  in  history revision:  see
  87.                     below for details.
  88.  
  89.                history words selector ?event?
  90.                     Retrieve from the command given by  event  (-1  by
  91.                     default)  the  words given by selector, and return
  92.                     those words in a string separated by spaces.   The
  93.                     selector  argument  has  three  forms.  If it is a
  94.                     single number then it selects the  word  given  by
  95.                     that  number  (0  for  the command name, 1 for its
  96.                     first argument, and so on).  If it consists of two
  97.                     numbers  separated  by a dash, then it selects all
  98.                     the  arguments  between  those   two.    Otherwise
  99.                     selector  is  treated  as  a  pattern;  all  words
  100.                     matching that pattern  (in  the  sense  of  string
  101.                     match)  are  returned.  In the numeric forms $ may
  102.                     be used to select the last word of a command.  For
  103.                     example,  suppose  the  most recent command in the
  104.                     history list is
  105.  
  106.                       format  {%s is %d years old} Alice [expr $ageInMonths/12]
  107.  
  108.                     Below are some history commands  and  the  results
  109.                     they would produce:
  110.  
  111.  
  112.                          history words $ 
  113.                                  [expr $ageInMonths/12]
  114.                          history words 1-2
  115.                                  {%s is %d years  old} Alice
  116.                          history words *a*o*
  117.                                  {%s is %d years old} [expr $ageInMonths/12]
  118.                     History words results in  history  revision:   see
  119.                     below for details.
  120.  
  121.                The history options event, redo, substitute, and  words
  122.                result  in  ``history  revision''.   When  one of these
  123.                options is invoked then the current event  is  modified
  124.                to  eliminate  the  history command and replace it with
  125.                the  result  of  the  history  command.   For  example,
  126.                suppose  that  the  most  recent command in the history
  127.                list is
  128.  
  129.                     set a [expr $b+2]
  130.  
  131.                and suppose that the next command invoked is one of the
  132.                ones  on the left side of the table below.  The command
  133.                actually recorded in the  history  event  will  be  the
  134.                corresponding one on the right side of the table.
  135.  
  136.  
  137.                     history                set a [expr $b+2]
  138.                     history s a b          set b [expr $b+2]
  139.                     set c [history w 2]    set c [expr $b+2]
  140.  
  141.                History revision is  needed  because  event  specifiers
  142.                like -1 are only valid at a particular time:  once more
  143.                events have been added to the history list a  different
  144.                event  specifier  would  be  needed.   History revision
  145.                occurs even when history is invoked indirectly from the
  146.                current event (e.g. a user types a command that invokes
  147.                a Tcl procedure that invokes history):   the  top-level
  148.                command   whose  execution  eventually  resulted  in  a
  149.                history command is replaced.  If  you  wish  to  invoke
  150.                commands  like  history words without history revision,
  151.                you can use history event to save the  current  history
  152.                event and then use history change to restore it later.
  153.